/* -*-c++-*- */
/* osgGIS - GIS Library for OpenSceneGraph
 * Copyright 2007-2008 Glenn Waldron and Pelican Ventures, Inc.
 * http://osggis.org
 *
 * osgGIS is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>
 */

#ifndef _OSGGIS_FEATURESTORE_H_
#define _OSGGIS_FEATURESTORE_H_ 1

#include <osgGIS/Common>
#include <osgGIS/Feature>
#include <osgGIS/FeatureCursor>
#include <osgGIS/SpatialReference>
#include <osgGIS/GeoExtent>
#include <sys/types.h>

namespace osgGIS
{
    /**
     * Interface to a feature data backing store.
     *
     * A FeatureStore holds an arbitrarily large collection of Feature objects.
     * This interface gives you access to that store, which is usually disk- or
     * network-based, without loading the whole thing into memory.
     *
     * Typically a FeatureLayer will sit atop a FeatureStore and provide access
     * to a spatial index (for fast geospatial searching) and layer-level 
     * attribution.
     */
	class OSGGIS_EXPORT FeatureStore : public osg::Referenced
	{
	public:
        /**
         * Gets whether a connection to the feature store was successfully
         * established.
         *
         * @return True if the connection is open; False if it failed to open.
         */
		virtual bool isReady() const =0;

        /**
         * Gets the name of the store.
         *
         * @return A humand-readable string
         */
        virtual const std::string& getName() const =0;
		
        /**
         * Gets the spatial reference system (SRS) of the geodata in the
         * store. This may be NULL is no SRS is specified.
         *
         * @return A spatial reference system
         */
		virtual SpatialReference* getSRS() const =0;
		
        /**
         * Gets the total number of features in the backing store.
         *
         * @return An integer count, or -1 if it cannot be determined
         */
		virtual int getFeatureCount() const =0;
		
        /**
         * Gets the bounding rectangle containing all the geodata
         * in the feature store.
         *
         * @return A spatial extent containing all features
         */
		virtual const GeoExtent& getExtent() const =0;
		
        /**
         * Gets an individual feature from the store.
         * 
         * @param oid
         *      Primary key (unique identifier) of the feature to get
         * @return
         *      Feature with the specified OID, or NULL if it does not exist
         */
		virtual Feature* getFeature( const FeatureOID& oid ) =0;
		
        /**
         * Creates a cursor that will iterator over ALL the features in
         * the backing store, in no particular order.
         *
         * @return A cursor for iterating over search results
         */
		virtual FeatureCursor getCursor() =0;
		
		/**
		 * Writes a feature to the feature store. The store must have been opened
         * for writing.
         *
         * @param feature
         *      Feature to insert. It must have the exact schema of the store.
         * @return
         *      True if inserting succeeded, false if it failed.
		 */
		virtual bool insertFeature( Feature* feature ) =0;

        /**
         * Creates and returns a new, empty feature instance. This method does NOT
         * insert the new feature into the store (see insertFeature). The called is
         * responsible for deallocating the returned object.
         */
        virtual Feature* createFeature() const =0;

        /**
         * Returns true if the feature store supports random access to
         * feature data (i.e. whether you can call getFeature(oid)).
         */
        virtual bool supportsRandomRead() const =0;
        
        /**
         * Gets the schema of each attribute in the feature store. User-defined
         * attributes added to individual features are not included.
         *
         * @return
         *      Attribute schema table
         */         
        virtual const AttributeSchemaTable& getAttributeSchemas() =0;

        /**
         * Gets the modification timestamp of the feature store source data.
         *
         * @return
         *      Raw modification timestamp
         */
        virtual const time_t getModTime() const =0;
	};
}


#endif // _OSGGIS_FEATURESTORE_H_
